# eric7.QScintilla.DocstringGenerator.PyDocstringGenerator

Module implementing a docstring generator for Python.

### Global Attributes

None

### Classes

PyDocstringGenerator | Class implementing a docstring generator for Python.
PyFunctionInfo | Class implementing an object to extract and store function information.

### Functions

None

## PyDocstringGenerator

Class implementing a docstring generator for Python.

### Derived from

BaseDocstringGenerator

### Class Attributes

None

### Class Methods

None

### Methods

PyDocstringGenerator | Constructor
__generateDocstring | Private method to generate the list of docstring lines.
__generateDocstringFromBelow | Private method to generate a docstring when the given position is on the line below the end of the definition.
__generateDocstringFromStart | Private method to generate a docstring based on the cursor being placed on the first line of the definition.
__getFunctionBody | Private method to get the function body.
__getFunctionDefinitionFromBelow | Private method to extract the function definition based on the cursor being placed on the first line after the definition.
__getFunctionDefinitionFromStart | Private method to extract the function definition based on the cursor being placed on the first line of the definition.
__getIndentationInsertString | Private method to create the indentation string for the docstring.
__isTripleQuotesStart | Private method to test, if the given text is the start of a triple quoted string.
hasFunctionDefinition | Public method to test, if the cursor is right below a function definition.
insertDocstring | Public method to insert a docstring for the function at the cursor position.
insertDocstringFromShortcut | Public method to insert a docstring for the function at the cursor position initiated via a keyboard shortcut.
isDocstringIntro | Public function to test, if the line up to the cursor position might be introducing a docstring.
isFunctionStart | Public method to test, if a text is the start of a function or method definition.

### Static Methods

None

#### PyDocstringGenerator (Constructor)

PyDocstringGenerator(editor)

Constructor

editor (Editor)
  reference to the editor widget

#### PyDocstringGenerator.__generateDocstring

__generateDocstring(quote, functionDef, bodyStartLine)

Private method to generate the list of docstring lines.

quote (str)
  quote string
functionDef (str)
  text containing the function definition
bodyStartLine (int)
  starting line of the function body

Return:
  list of docstring lines

Return Type:
  list of str

#### PyDocstringGenerator.__generateDocstringFromBelow

__generateDocstringFromBelow(cursorPosition)

Private method to generate a docstring when the given position is on the line below the end of the definition.

cursorPosition (tuple of (int, int))
  position of the cursor (line and index)

Return:
  tuple containing the docstring and a tuple containing the insertion line and index

Return Type:
  tuple of (str, tuple(int, int))

#### PyDocstringGenerator.__generateDocstringFromStart

__generateDocstringFromStart()

Private method to generate a docstring based on the cursor being placed on the first line of the definition.

Return:
  tuple containing the docstring and a tuple containing the insertion line and index

Return Type:
  tuple of (str, tuple(int, int))

#### PyDocstringGenerator.__getFunctionBody

__getFunctionBody(functionIndent, startLine)

Private method to get the function body.

functionIndent (str)
  indentation string of the function definition
startLine (int)
  starting line for the extraction process

Return:
  text containing the function body

Return Type:
  str

#### PyDocstringGenerator.__getFunctionDefinitionFromBelow

__getFunctionDefinitionFromBelow(cursorPosition)

Private method to extract the function definition based on the cursor being placed on the first line after the definition.

cursorPosition (tuple of (int, int))
  current cursor position (line and column)

Return:
  text containing the function definition

Return Type:
  str

#### PyDocstringGenerator.__getFunctionDefinitionFromStart

__getFunctionDefinitionFromStart()

Private method to extract the function definition based on the cursor being placed on the first line of the definition.

Return:
  text containing the function definition

Return Type:
  str

#### PyDocstringGenerator.__getIndentationInsertString

__getIndentationInsertString(text)

Private method to create the indentation string for the docstring.

text (str)
  text to based the indentation on

Return:
  indentation string for docstring

Return Type:
  str

#### PyDocstringGenerator.__isTripleQuotesStart

__isTripleQuotesStart(text)

Private method to test, if the given text is the start of a triple quoted string.

text (str)
  text to be inspected

Return:
  flag indicating a triple quote start

Return Type:
  bool

#### PyDocstringGenerator.hasFunctionDefinition

hasFunctionDefinition(cursorPosition)

Public method to test, if the cursor is right below a function definition.

cursorPosition (tuple of (int, int))
  current cursor position (line and column)

Return:
  flag indicating cursor is right below a function definition

Return Type:
  bool

#### PyDocstringGenerator.insertDocstring

insertDocstring(cursorPosition, fromStart=True)

Public method to insert a docstring for the function at the cursor position.

cursorPosition (tuple of (int, int))
  position of the cursor (line and index)
fromStart (bool)
  flag indicating that the editor text cursor is placed on the line starting the function definition

#### PyDocstringGenerator.insertDocstringFromShortcut

insertDocstringFromShortcut(cursorPosition)

Public method to insert a docstring for the function at the cursor position initiated via a keyboard shortcut.

cursorPosition (tuple of (int, int))
  position of the cursor (line and index)

#### PyDocstringGenerator.isDocstringIntro

isDocstringIntro(cursorPosition)

Public function to test, if the line up to the cursor position might be introducing a docstring.

cursorPosition (tuple of (int, int))
  current cursor position (line and column)

Return:
  flag indicating a potential start of a docstring

Return Type:
  bool

#### PyDocstringGenerator.isFunctionStart

isFunctionStart(text)

Public method to test, if a text is the start of a function or method definition.

text (str)
  line of text to be tested

Return:
  flag indicating that the given text starts a function or method definition

Return Type:
  bool

Up

## PyFunctionInfo

Class implementing an object to extract and store function information.

### Derived from

FunctionInfo

### Class Attributes

None

### Class Methods

None

### Methods

PyFunctionInfo | Constructor
__findBracketPosition | Private method to find the start and end position of pairs of brackets.
__findQuotePosition | Private method to find the start and end position of pairs of quotes.
__isCharInPairs | Private method to test, if the given character position is between pairs of brackets or quotes.
__splitArgumentToNameTypeValue | Private method to split some argument text to name, type and value.
__splitArgumentsTextToList | Private method to split the given arguments text into a list of arguments.
parseBody | Public method to parse the function body text.
parseDefinition | Public method to parse the function definition text.

### Static Methods

None

#### PyFunctionInfo (Constructor)

PyFunctionInfo()

Constructor

#### PyFunctionInfo.__findBracketPosition

__findBracketPosition(text, bracketLeft, bracketRight, posQuote)

Private method to find the start and end position of pairs of brackets.

https://stackoverflow.com/questions/29991917/ indices-of-matching-parentheses-in-python

text (str)
  text to be parsed
bracketLeft (str)
  character of the left bracket
bracketRight (str)
  character of the right bracket
posQuote (list of tuple of (int, int))
  list of tuple with start and end position of pairs of quotes

Return:
  list of tuple with start and end position of pairs of brackets

Return Type:
  list of tuple of (int, int)

Raises IndexError:
  raised when a closing or opening bracket is missing

#### PyFunctionInfo.__findQuotePosition

__findQuotePosition(text)

Private method to find the start and end position of pairs of quotes.

text (str)
  text to be parsed

Return:
  list of tuple with start and end position of pairs of quotes

Return Type:
  list of tuple of (int, int)

Raises IndexError:
  raised when a matching close quote is missing

#### PyFunctionInfo.__isCharInPairs

__isCharInPairs(posChar, pairs)

Private method to test, if the given character position is between pairs of brackets or quotes.

posChar (int)
  character position to be tested
pairs (list of tuple of (int, int))
  list containing pairs of positions

Return:
  flag indicating the position is in between

Return Type:
  bool

#### PyFunctionInfo.__splitArgumentToNameTypeValue

__splitArgumentToNameTypeValue(argumentsList, quote, quoteReplace)

Private method to split some argument text to name, type and value.

argumentsList (list of str)
  list of function argument definitions
quote (str)
  quote string to be replaced
quoteReplace (str)
  quote string to replace the original

#### PyFunctionInfo.__splitArgumentsTextToList

__splitArgumentsTextToList(argumentsText)

Private method to split the given arguments text into a list of arguments.

This function uses a comma to separate arguments and ignores a comma in brackets and quotes.

argumentsText (str)
  text containing the list of arguments

Return:
  list of individual argument texts

Return Type:
  list of str

#### PyFunctionInfo.parseBody

parseBody(text)

Public method to parse the function body text.

text (str)
  function body text

#### PyFunctionInfo.parseDefinition

parseDefinition(text, quote, quoteReplace)

Public method to parse the function definition text.

text (str)
  text containing the function definition
quote (str)
  quote string to be replaced
quoteReplace (str)
  quote string to replace the original

Up